<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html><head>
<meta http-equiv="Content-Language" content="en-us">

<title>The sandbox script</title><link rel="stylesheet" type="text/css" href="../style.css"></head>


<body>

<div align="center">
<table class="allEncompassingTable">
 <tbody><tr>
  <td>
<p><a href="../index.html" target="_top"><img src="images/homeImg.png"></a></p>



<h1>The sandbox script</h1>

<p>The sandbox script is quite similar to an <a href="addOns.htm">add-on script</a>:
it is automatically loaded at program start-up, and allows CoppeliaSim's
functionality to be extended by user-written functionality or
functions. In addition to that, the sandbox script is extensively used in CoppeliaSim's  Lua commander plugin (read-eval-print loop), that adds a text input to the CoppeliaSim status bar, allowing entering and executing Lua code on the fly, like in a terminal. It is persistent across all opened scenes, and is executed
constantly, effectively running in the
background. For that reason, it should only execute minimalistic code everytime called, since the whole application would otherwise slow down.
The sandbox script is called frequently by the system, with a <a href="scriptExecution.htm">precise order</a>.</p>

<p>The sandbox script is loaded from <em>system/sndbxscpt.txt</em> at start-up, and should be segmented into several system callback functions, as following skeleton script illustrates: </p>


<pre class=lightRedBox>
function <strong>sysCall_init</strong>() -- not optional!
    -- do some initialization here
end

function <strong>sysCall_cleanup</strong>()
    -- do some clean-up here
end

function <strong>sysCall_nonSimulation</strong>()
    -- is executed when simulation is not running
end

function <strong>sysCall_beforeSimulation</strong>()
    -- Simulation is about to start
end

function <strong>sysCall_beforeMainScript</strong>()
    -- Can be used to step a simulation in a custom manner.
    local outData={doNotRunMainScript=false} -- when true, then the main script won't be executed
    return outData
end

function <strong>sysCall_actuation</strong>()
    -- put some actuation code here.
end

function <strong>sysCall_sensing</strong>()
    -- put some sensing code here.
end

function <strong>sysCall_afterSimulation</strong>()
    -- Simulation has just ended
end

function <strong>sysCall_suspend</strong>()
    -- Simulation is about to be suspended
end

function <strong>sysCall_suspended</strong>()
    -- Simulation is suspended
end

function <strong>sysCall_resume</strong>()
    -- Simulation is about to resume
end

function <strong>sysCall_beforeInstanceSwitch</strong>()
    -- About to switch to another scene
end

function <strong>sysCall_afterInstanceSwitch</strong>()
    -- Switched to another scene
end

function <strong>sysCall_beforeCopy</strong>(inData)
    for key,value in pairs(inData.objectHandles) do
        print("Object with handle "..key.." will be copied")
    end
end

function <strong>sysCall_afterCopy</strong>(inData)
    for key,value in pairs(inData.objectHandles) do
        print("Object with handle "..key.." was copied")
    end
end

function <strong>sysCall_beforeDelete</strong>(inData)
    for key,value in pairs(inData.objectHandles) do
        print("Object with handle "..key.." will be deleted")
    end
    -- inData.allObjects indicates if all objects in the scene will be deleted
end

function <strong>sysCall_afterDelete</strong>(inData)
    for key,value in pairs(inData.objectHandles) do
        print("Object with handle "..key.." was deleted")
    end
    -- inData.allObjects indicates if all objects in the scene were deleted
end

function <strong>sysCall_afterCreate</strong>(inData)
    for i=1,#inData.objectHandles,1 do
        print("Object with handle "..inData.objectHandles[i].." was created")
    end
end</pre>


<p>The sandbox script can call any of the <a href="apiOverview.htm">regular API functions</a>, as long as not stated otherwise in the documentation. It can even call custom Lua functions registered by <a href="plugins.htm">plugins</a>. It however has two restrictions:</p>
<li>The sandbox script cannot call API functions that require the caller to run in
a thread. This is because the sandbox script operates in a non-threaded fashion.</li>

<br>
<br>
<h3 class="recommendedTopics">Recommended topics</h3>
<li><a href="http://www.lua.org">Lua</a></li>
<li><a href="addOns.htm">Add-ons</a></li>
<li><a href="apiFunctionListAlphabetical.htm">Regular API functions</a></li>
<br>
<br>
 </td></tr>
</tbody></table> 
</div>  
  
  
</body></html>